/*-------------------------------------------------------------------------
 *
 * resowner.h
 *	  POSTGRES 资源所有者定义。
 *
 * 查询生命周期资源通过将它们与
 * ResourceOwner 对象关联来进行跟踪。这提供了一种简单机制，确保
 * 这些资源在正确的时间被释放。
 * 有关更多信息，请参见 utils/resowner/README。
 *
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/utils/resowner.h
 *
 *-------------------------------------------------------------------------*/
#ifndef RESOWNER_H
#define RESOWNER_H


/*
 * ResourceOwner 对象是一个仅在 resowner.c 内部已知的透明数据结构。
 */
typedef struct ResourceOwnerData *ResourceOwner;


/*
 * 全局已知的 ResourceOwners
 */
extern PGDLLIMPORT ResourceOwner CurrentResourceOwner;
extern PGDLLIMPORT ResourceOwner CurTransactionResourceOwner;
extern PGDLLIMPORT ResourceOwner TopTransactionResourceOwner;
extern PGDLLIMPORT ResourceOwner AuxProcessResourceOwner;

/*
 * 资源释放分为三个阶段：预锁、锁定和后锁。预锁阶段必须释放任何
 * 对其他后端可见的资源（例如固定的缓冲区）；这确保当我们释放一个
 * 其他后端可能正在等待的锁时，它会看到我们已完全退出交易。后锁
 * 阶段应用于后端内部的清理。
 */
typedef enum
{
	RESOURCE_RELEASE_BEFORE_LOCKS,
	RESOURCE_RELEASE_LOCKS,
	RESOURCE_RELEASE_AFTER_LOCKS
} ResourceReleasePhase;

/*
 * 动态加载的模块可以通过提供这种形式的回调在 ResourceOwnerRelease
 * 中获得控制。
 */
typedef void (*ResourceReleaseCallback) (ResourceReleasePhase phase,
										 bool isCommit,
										 bool isTopLevel,
										 void *arg);


/*
 * Functions in resowner.c
 */

/* 通用例程 */
extern ResourceOwner ResourceOwnerCreate(ResourceOwner parent,
										 const char *name);
extern void ResourceOwnerRelease(ResourceOwner owner,
								 ResourceReleasePhase phase,
								 bool isCommit,
								 bool isTopLevel);
extern void ResourceOwnerReleaseAllPlanCacheRefs(ResourceOwner owner);
extern void ResourceOwnerDelete(ResourceOwner owner);
extern ResourceOwner ResourceOwnerGetParent(ResourceOwner owner);
extern void ResourceOwnerNewParent(ResourceOwner owner,
								   ResourceOwner newparent);
extern void RegisterResourceReleaseCallback(ResourceReleaseCallback callback,
											void *arg);
extern void UnregisterResourceReleaseCallback(ResourceReleaseCallback callback,
											  void *arg);
extern void CreateAuxProcessResourceOwner(void);
extern void ReleaseAuxProcessResources(bool isCommit);

#endif							/* RESOWNER_H */
